Skip to content

feat(chat): Draw a reply's Markdown instead of its source - #705

Merged
omesser merged 4 commits into
mainfrom
feat/677-markdown-js-lib
Sep 15, 2026
Merged

omesser merged 4 commits into
mainfrom
feat/677-markdown-js-lib

Conversation

@omesser

@omesser omesser commented Sep 14, 2026 •

Copy link
Copy Markdown
Owner

Why

A reply was drawn as its source text, so Markdown a model emits reached the user as punctuation: **bold** showed the asterisks, a bulleted list stayed a run of hyphens, fenced code had no code styling. Harnesses emit Markdown by default and cannot be asked not to, so almost every substantial reply read worse than the model wrote it.

This lands after #702, which stopped parse_proposal flattening a reply's line breaks. That fix was a prerequisite: Markdown is newline-significant, and a renderer handed a space-joined line cannot recover lists, paragraphs or fences. The two compose — #702 makes the structure survive, this draws it.

What it looks like

A reply's Markdown, drawn beside its source text

The same Harness reply, both ways, at the real 420-point column width: on the
left what the user sees today, on the right what this branch draws. Bold, inline
code, a bulleted list, a fenced block with its language, and a link.

Rendered by this branch's own src/markdown.js and src/chat-ui.css — the
production renderer and the production stylesheet, on the real .row.them /
.said.md structure chat.js builds. Captured in headless Chrome, not in
the app's WKWebView
, so it proves the renderer and the CSS rather than the
embedding; the caret and the live click are not in it. Checked into the
repository and linked by commit SHA per docs/agents/writing.md — the gh
CLI cannot attach an image, and a branch link dies on the squash merge.

What changed, and why it is in the webview

Markdown formatting is drawing, not state. It is derived deterministically from the reply text and carries no authority. This repo states that split in four places — src/main.js:1 ("The webview draws the Characters and owns none of their state"), src/chat.js:8, src-tauri/src/main.rs:411, and most precisely CONTEXT.md:288: "Engine names the Cue on the frame; the webview draws and synthesizes it." The Cue is the same shape: the Engine makes the semantic decision, the webview turns it into pixels.

Two other approaches were built and rejected. A hand-rolled JS parser owned 216 lines of CommonMark logic we would have to keep correct — and it shipped a DOMException in the streaming path plus ***bold-italic*** rendering with stray asterisks. A Rust pulldown-cmark parse shipping tokens over IPC put a presentation concern behind a serialization boundary, so every future view decision — syntax highlighting, collapsible fences, a per-block copy button — would become a cross-language change plus a new serde variant on both sides. The full comparison, with numbers, is on #677.

  • src/vendor/marked.esm.js — marked@18.0.13, 78 lines / 44,963 bytes, zero imports, zero runtime dependencies. Vendored because tauri.conf.json is "frontendDist": "../src" with CSP default-src 'self': no build step, no bundler, and a CDN import is blocked. Provenance, reproduce command and sha256 are in src/vendor/README.md, and a test asserts the hash so an in-place edit fails loudly.
  • src/markdown.js — 244 lines that contain no parsing. It is a token-to-DOM switch over marked's AST, building elements with createElement and textContent.

Why marked, and why GFM

Selected on fidelity to what Harnesses actually emit, since this is a Harness client. The evidence says GFM, not bare CommonMark: Codex ships its prompt in the open and emits pipe tables anyway (openai/codex#22015); Claude Code has its own table, task-list and strikethrough issues; the ACP adapter generates Markdown, growing a code fence until it is longer than anything inside it, so 4+ backtick fences arrive on the wire; Zed, the reference ACP client, renders agent chunks with ENABLE_TABLES | ENABLE_STRIKETHROUGH | ENABLE_TASKLISTS plus a linkify pass; and VS Code vendors marked verbatim and renders chat through its token API (markedInstance.lexer()), with a dedicated file for wrapping agent tables in a scroll container — the same architecture, arrived at independently.

Rejected: markdown-it (self-contained ESM is minified-only at 138 KB, 2 of 4 GFM features by default, flat open/close tokens rather than a tree), commonmark.js (real AST but no tables, strikethrough, task lists or autolinks — exactly what agents emit), micromark/mdast (need a bundler), snarkdown (HTML string, no AST), markdown-wasm (needs wasm-unsafe-eval).

Security

No HTML string is ever produced. marked's HTML writer is not used; the token API feeds createElement + textContent, which makes injection structurally impossible rather than sanitized after the fact. A reply is untrusted — model output, steerable by an MCP server's content.

Links open in the user's browser. A link renders as <span class="md-link" data-href> — deliberately not an <a href>, because there is no shell or opener plugin in tauri.conf.json and nothing intercepts navigation, so an href would take the chat window itself to the page and the conversation with it. default-src 'self' does not stop a top-level navigation, and neither target="_blank" nor window.open reaches the system browser from a webview. Only the native side can hand a URL to the OS.

So: one delegated click listener on the log invokes a new open_link command, which calls platform::open_url.

The scheme gate is in Rust, at the last edge before the OS, so no caller can route around it — src/markdown.js filters too, and neither check trusts the other. It is decided by parsing with the url crate (already a dependency) rather than by matching a prefix, which is what makes JaVaScRiPt:, &#106;avascript:, java<tab>script: and a leading newline all resolve to the scheme they really are and get refused. http, https and mailto pass; a refused scheme returns an error rather than silently doing nothing, so a dead link can be told from a turned-away one.

Two details that are easy to get wrong and are worth a reviewer's eye:

  • open_url is a sibling of open_path, not a widening of it. open_path calls ensure_file first, so a URL handed to it would be created on disk as a file named after the URL. The two share the per-platform opener below them, which is the only part that actually differs.
  • What reaches the OS is the parsed form, never the caller's string. They differ — parsing normalises — and validating one while opening the other is how a gate gets walked past. A test pins it: " https://example.com " opens as https://example.com/.

The per-platform opener is now &OsStr rather than &Path so both entry points share it. All three arms already accept a URL: macOS open, Linux xdg-open, Windows ShellExecuteW. Command execs directly with no shell, so there is no metacharacter to quote, and a parsed URL always starts with its scheme so it can never be read as an option flag.

How to verify

node --test tests/
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings

181 node tests pass, 448 Rust tests pass, clippy clean. grep -n 'innerHTML\|insertAdjacentHTML\|outerHTML\|document.write' src/*.js returns nothing — and that is now asserted by a test, sweeping src/ and src/vendor/ for innerHTML, eval( and new Function. It was true by construction before and nothing enforced it.

14 adversarial payloads, run rather than reasoned: <script>alert(1)</script>, <img src=x onerror=alert(1)>, <iframe src=javascript:alert(1)>, [x](javascript:alert(1)), [x](data:text/html,…), JaVaScRiPt:, &#106;avascript:, \njavascript:, java\tscript:, vbscript:, an unterminated fence, and a malformed table. Two tests assert over all of them: no element outside a 26-tag allowlist is ever built, and no node carries an href or data-href that is not https?: or mailto:.

Streaming. drawSaid reads the caret, removes it, rebuilds, re-appends — no insertBefore anywhere, so the NotFoundError that broke the hand-rolled branch cannot occur; there is no reference node to be wrong about. Tests stream four chunks, one landing mid-marker, asserting after each that the caret is still in the row, is the same node, and appears once. The DOM stand-in's insertBefore asserts its reference node is a child — the permissive version is what hid that bug.

The scheme gate was mutation-tested. Disabling the allowlist (if false) fails a_link_that_runs_or_reads_does_not_open and an_obfuscated_scheme_is_still_that_scheme; restored from a scratch copy, never git checkout, with the tree clean after. Four gate tests cover the three allowed schemes, the four that run or read (javascript, data, vbscript, file), seven obfuscated spellings of javascript:, and the parsed-not-original property.

11 mutations run. Nine killed. Two survived and were real findings, not test gaps: a caret?.remove() that replaceChildren already made redundant (deleted), and an unreachable branch in inline() (deleted). A third survived until a test was added for formatting inside a list item — a case the suite genuinely lacked.

Notes

  • Supported: paragraphs, ATX headings, tight and loose lists, nested lists, ordered lists with a start offset, GFM task lists, nested blockquotes, thematic breaks, fenced code with an info string (any fence length), indented code, GFM tables with per-column alignment, bold, italic, both, strikethrough, inline code, hard breaks, backslash escapes, inline links and bare-URL autolinks.
  • Deliberately not supported, each reading as the source the model wrote: images (CSP is img-src 'self' data:, so a model-supplied remote image cannot load and fetching one would be a beacon), raw HTML inline and block (this is the security property, not a gap), footnotes, HTML entities (marked leaves them in token text for its HTML writer; decoding would mean owning a 2000-name table), and syntax highlighting (the info string sets a language-* class that nothing reads yet).
  • The vendored file is minified, and that was not a free choice. marked has published no readable ESM since v16 — 15.0.12 is 2189 readable lines; 16.4.1 through 18.0.13 are 72–78 minified. Taking the readable one means pinning 15.x and giving up three majors. Standing in for reading it: a pinned version, a registry-matching sha256 asserted by a test, npm SLSA provenance, and the eval/new Function sweep above.
  • Not the smallest option. 1039 insertions against the hand-roll's 866. Footprint was the wrong metric; the right one is lines of CommonMark we own, which is zero.
  • Never run in a real webview. The renderer is verified against a spec-strict DOM stand-in; the CSS — block margins, fence and table overflow-x at the chat width, link styling, the caret inside the last paragraph — is visually unverified. True of all three candidate branches.
  • Four pre-commit hooks are excluded for the vendored file. Only codespell actually bites today (it flags minifier identifiers), but a fixer silently rewriting a hash-pinned third-party parser is corruption; .b64 files carry the same exclusion for the same reason.

Closes #677

— Claude Code agent, on @omesser's behalf.

🤖 Generated with Claude Code

@omesser

omesser commented Sep 14, 2026

Copy link
Copy Markdown
Owner Author

CI failure diagnosed and fixed in 7ef756d1. It had nothing to do with Markdown.

checks (macos-latest) and checks (ubuntu-latest) failed on Pretty format TOML wanting to respace every inline table in src-tauri/Cargo.toml — a file this branch does not touch. git diff origin/main...HEAD -- src-tauri/Cargo.toml is empty.

Root cause. The hook repo pins toml-sort>=0.22.0 (setup.cfg:33) — an unbounded lower bound, so a fresh install takes whatever is newest. That is now 0.25.0, which formats {version = "x"} as { version = "x" }. My own machine had two different versions cached already (0.24.2 and 0.24.4), which is the same drift showing up locally.

Why main is green and this branch was not. CI caches the pre-commit environment keyed on .pre-commit-config.yaml. main has never re-resolved, so it runs an old toml-sort and passes. This branch edits that file to exclude the vendored library from four fixers, which changes the key, forces a fresh install, and picks up 0.25.0. Any branch editing .pre-commit-config.yaml would have hit this — the failure was latent, not introduced here.

Fix: pin toml-sort==0.24.4 via additional_dependencies on the hook, so every environment formats identically. Cargo.toml is left alone — adopting 0.25.0's style is a deliberate change with its own reformat commit, not something a cache miss should do silently.

Verified against a cold environment rather than my warm cache, since the warm one was what hid this:

PRE_COMMIT_HOME=<fresh dir> pre-commit run pretty-format-toml --all-files
# [INFO] Installing environment for .../language-formatters-pre-commit-hooks.
# Pretty format TOML.......................................................Passed
# installed: toml_sort-0.24.4
# git status --porcelain -- src-tauri/Cargo.toml  ->  (empty)

154 node tests still pass.

— Claude Code agent, on @omesser's behalf.

omesser and others added 2 commits September 15, 2026 16:28
Third approach to #677: parse in the webview, with a vendored library.
GFM, because that is the flavour harnesses emit. Tokens to DOM nodes, so
the reply never reaches markup. The caret is moved with append, never
insertBefore.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The webview cannot do this itself: there is no opener plugin and nothing
intercepts navigation, so an <a href> would take the chat window to the
page and the conversation with it. The scheme gate sits at the last edge
before the OS so no caller routes around it, and it parses rather than
prefix-matches, because a link target is model output.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@omesser
omesser force-pushed the feat/677-markdown-js-lib branch from 7ef756d to f7221a6 Compare September 15, 2026 13:33
The &OsStr change missed a #[cfg(not(unix))] call site, which no local
build can see. Type-checked this time by extracting the arm into a
scratch crate for x86_64-pc-windows-msvc, since ring's build script
cannot compile whole-crate without MSVC headers.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@omesser

omesser commented Sep 15, 2026

Copy link
Copy Markdown
Owner Author

Windows CI failure fixed in 81376fe6, and type-checked for Windows this time rather than pushed on hope.

What broke. Generalising the per-platform opener from &Path to &OsStr — so open_path and the new open_url can share it — left one call site behind: windows_opener_keeps_ampersand_percent_and_space at platform.rs:1296 still passed a &Path to shell_execute_file_wide. It is #[cfg(not(unix))], so no build on this Mac can see it. cargo test, cargo clippy --workspace and pre-commit were all green locally while the Windows clippy job failed with E0308. The compiler had already caught the unix twin of the same mistake; the Windows one had nothing to catch it.

Audited rather than patched one-by-one. Every call site of both changed functions, cfg'd-out ones included: opener( has three definitions and one test caller; shell_execute_file_wide( has one caller and one test caller. All now pass &OsStr. The other #[cfg(not(unix))] test calls open_path, whose signature is unchanged.

How it is verified now. cargo clippy --target x86_64-pc-windows-msvc -p ai-buddy cannot run here — it dies in ring's build script for want of MSVC headers (fatal error: 'assert.h' file not found), which is environmental and predates this branch. So I extracted the Windows arm verbatim — opener, shell_execute_file_wide, and the test — into a scratch crate with windows-sys at the same version and features:

$ cargo clippy --target x86_64-pc-windows-msvc --all-targets -- -D warnings
    Checking wincheck705 v0.0.0
    Finished `dev` profile

And confirmed that check is not vacuous, by reintroducing exactly the bug CI caught:

$ # shell_execute_file_wide(path) instead of path.as_os_str()
error[E0308]: mismatched types
   |  ----------------------- ^^^^ expected `&OsStr`, found `&Path`

It reproduces CI's failure locally and passes when fixed.

cargo test -p ai-buddy 448 passed. cargo clippy --workspace --all-targets -- -D warnings clean. node --test tests/ 181 passed.

Still true and worth keeping in view: the Windows arm is type-checked, not run. Nothing here executes ShellExecuteW, so that a URL actually opens in the default browser on Windows is unverified by me — CI compiles it, and the first real run is someone on Windows. #715 tracks the platform evidence this repo cannot gather on a Mac.

— Claude Code agent, on @omesser's behalf.

A reviewer approves on the diff, and the diff is the one thing that
cannot show them a rendered list. Checked in rather than attached: the
gh CLI cannot upload, and a link to a branch dies on the squash merge.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@omesser
omesser merged commit b1458b8 into main Sep 15, 2026
5 checks passed
@omesser
omesser deleted the feat/677-markdown-js-lib branch September 15, 2026 15:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(chat): Render Markdown in a reply instead of its source

1 participant